home *** CD-ROM | disk | FTP | other *** search
/ Mac Easy 2010 May / Mac Life Ubuntu.iso / casper / filesystem.squashfs / usr / share / gnome / help / gnome-doc-make / C / gnome-doc-make.xml next >
Encoding:
Extensible Markup Language  |  2009-03-17  |  21.2 KB  |  598 lines
  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!-- -*- indent-tabs-mode: nil -*- -->
  3. <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
  4. "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
  5. <article id="index" lang="en">
  6.   <articleinfo>
  7.     <title>GNOME Documentation Build Utilities</title>
  8.  
  9.     <abstract role="description">
  10.       <para>The GNOME Documentation Build Utilities were created to make it
  11.       easier for application developers to include and create documentation in
  12.       their releases.</para>
  13.     </abstract>
  14.  
  15.     <copyright>
  16.       <year>2004</year>
  17.  
  18.       <holder>Shaun McCance</holder>
  19.     </copyright>
  20.  
  21.     <publisher>
  22.       <publishername>GNOME Documentation Project</publishername>
  23.     </publisher>
  24.  
  25.     <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" />
  26.  
  27.     <authorgroup>
  28.       <author role="maintainer">
  29.         <firstname>Shaun</firstname>
  30.  
  31.         <surname>McCance</surname>
  32.  
  33.         <affiliation>
  34.           <orgname>GNOME Documentation Project</orgname>
  35.         </affiliation>
  36.  
  37.         <email>shaunm@gnome.org</email>
  38.       </author>
  39.  
  40.       <author>
  41.         <firstname>Brent</firstname>
  42.  
  43.         <surname>Smith</surname>
  44.  
  45.         <affiliation>
  46.           <orgname>GNOME Documentation Project</orgname>
  47.         </affiliation>
  48.  
  49.         <email>gnome@nextreality.net</email>
  50.       </author>
  51.     </authorgroup>
  52.  
  53.     <revhistory>
  54.       <revision>
  55.         <revnumber>0.1</revnumber>
  56.  
  57.         <date>2004-07-08</date>
  58.       </revision>
  59.  
  60.       <revision>
  61.         <revnumber>0.2</revnumber>
  62.  
  63.         <date>2006-02-04</date>
  64.       </revision>
  65.     </revhistory>
  66.   </articleinfo>
  67.  
  68.   <section id="intro">
  69.     <title>Introduction</title>
  70.  
  71.     <para>The GNOME Documentation Build Utilities were created to make it
  72.     easier for application developers to include and create documentation in
  73.     their releases.</para>
  74.  
  75.     <para>There are several advantages to using gnome-doc-utils in your
  76.     application:</para>
  77.  
  78.     <para>
  79.       <orderedlist>
  80.         <listitem>
  81.           <para>Translation is made much easier through the use of
  82.           <application>xml2po</application>, which generates standard
  83.           <filename>.po</filename> files from docbook/xml.</para>
  84.         </listitem>
  85.  
  86.         <listitem>
  87.           <para>OMF file creation is automated from a template file for all
  88.           translated languages.</para>
  89.         </listitem>
  90.  
  91.         <listitem>
  92.           <para>Installation of documentation is automated.</para>
  93.         </listitem>
  94.       </orderedlist>
  95.     </para>
  96.  
  97.     <para>GNOME Documentation Build Utilities are named
  98.     <application>gnome-doc-utils</application> on the GNOME CVS server, so we
  99.     will refer to them in this manner throughout the rest of this
  100.     document.</para>
  101.   </section>
  102.  
  103.   <section id="migrating">
  104.     <title>Migrating to GNOME Documentation Build Utilities</title>
  105.  
  106.     <para>Many applications use an older method of including documentation. It
  107.     is our intention that these applications switch over to gnome-doc-utils to
  108.     provide a uniform method for building and installing documentation. The
  109.     following instructions should help you to set up new documentation or port
  110.     existing documentation to gnome-doc-utils.</para>
  111.  
  112.     <section>
  113.       <title>Requirements</title>
  114.  
  115.       <para>Make sure you're using recent
  116.       <application>gnome-common</application> (from 2005-07-19 or later) if
  117.       you're using <filename>gnome-autogen.sh</filename>, or call
  118.       <application>gnome-doc-prepare</application> in your
  119.       <filename>autogen.sh</filename> by hand.</para>
  120.     </section>
  121.  
  122.     <section>
  123.       <title>Setting up <filename>help/Makefile.am</filename></title>
  124.  
  125.       <para>The standard location for documentation is in a subdir named
  126.       <filename>help/</filename> in your directory structure. This name is not
  127.       mandatory, although it is recommended. There should also be a
  128.       <filename>help/C/</filename> subdirectory which contains the help
  129.       document as <literal>document-name.xml</literal>.</para>
  130.  
  131.       <para>In the <filename>help</filename> directory, create a file named
  132.       <filename>Makefile.am</filename>. Define the following variables inside
  133.       the file:</para>
  134.  
  135.       <para><programlisting>include $(top_srcdir)/gnome-doc-utils.make
  136. dist-hook: doc-dist-hook
  137.  
  138. DOC_MODULE = document-name
  139. DOC_ENTITIES = legal.xml
  140. DOC_INCLUDES = filename.c
  141. DOC_FIGURES = figures/main_window.png      \
  142.               figures/open_document.png
  143.  
  144. DOC_LINGUAS = es sr uk</programlisting>Here is a brief description of what
  145.       each variable does:</para>
  146.  
  147.       <para>
  148.         <variablelist>
  149.           <varlistentry>
  150.             <term>DOC_MODULE</term>
  151.  
  152.             <listitem>
  153.               <para>The name of the help document to build. This is the
  154.               filename without the <literal>.xml</literal> extension. You
  155.               should have help/C/$DOC_MODULE.xml</para>
  156.             </listitem>
  157.           </varlistentry>
  158.  
  159.           <varlistentry>
  160.             <term>DOC_ENTITIES</term>
  161.  
  162.             <listitem>
  163.               <para>List any files included in the help document using system
  164.               entities.</para>
  165.  
  166.               <para>Example: <code><!ENTITY SYSTEM
  167.               "chapter1.xml"></code></para>
  168.             </listitem>
  169.           </varlistentry>
  170.  
  171.           <varlistentry>
  172.             <term>DOC_INCLUDES</term>
  173.  
  174.             <listitem>
  175.               <para>List any files that are included with the <ulink
  176.               url="???">Xinclude</ulink> specification.</para>
  177.             </listitem>
  178.           </varlistentry>
  179.  
  180.           <varlistentry>
  181.             <term>DOC_FIGURES</term>
  182.  
  183.             <listitem>
  184.               <para>List all the figures that are referenced in the help
  185.               document.</para>
  186.             </listitem>
  187.           </varlistentry>
  188.  
  189.           <varlistentry>
  190.             <term>DOC_LINGUAS</term>
  191.  
  192.             <listitem>
  193.               <para>List all the language codes for the languages in which the
  194.               document is currently translated.</para>
  195.             </listitem>
  196.           </varlistentry>
  197.         </variablelist>
  198.       </para>
  199.     </section>
  200.  
  201.     <section>
  202.       <title>Setting Up <filename>help/document-name.omf.in</filename></title>
  203.  
  204.       <para>GNOME Documentation Build Utilities require a template OMF file be
  205.       installed at <filename>help/document-name.omf.in</filename>. This file
  206.       contains a stripped down version of a Scrollkeeper OMF file. If you are
  207.       porting documentation, you can modify your existing OMF file (and rename
  208.       it) to meet these requirements.</para>
  209.  
  210.       <para><emphasis>PLEASE</emphasis> remember to change the documentation
  211.       license if you are not using the GFDL. The GNOME documentation project
  212.       does not endorse or recommend the use of this license without
  213.       understanding the full implications of doing so.</para>
  214.  
  215.       <example id="example-omf-template">
  216.         <title>Example of a OMF file template</title>
  217.  
  218.         <programlisting><?xml version="1.0" standalone="no"?>
  219. <omf>
  220.   <resource>
  221.     <subject category="GNOME|Tutorials"/>
  222.     <type>manual</type>
  223.     <relation seriesid="b57e7e48-be78-11d6-85a3-d094906a987c"/>
  224.     <rights type="GNU FDL" license.version="1.1" holder="Shaun McCance"/>
  225.   </resource>
  226. </omf></programlisting>
  227.       </example>
  228.  
  229.       <para>
  230.         <warning>
  231.           <para>If you are porting documentation to gnome-doc-utils, use the
  232.           the same <code>seriesid</code> attribute on the
  233.           <code>relation</code> element as defined in your old OMF file. This
  234.           will ensure that when the new documentation gets installed, it will
  235.           get replace the older version of the document.</para>
  236.         </warning>
  237.       </para>
  238.  
  239.       <para>GNOME Documentation Build Utilities will create a
  240.       <filename>document-name-C.omf</filename> and an additional
  241.       <filename>document-name-<locale>.omf</filename> for each language
  242.       code defined in the DOC_LINGUAS variable in
  243.       <filename>Makefile.am</filename>. Depending on certain elements present
  244.       in the help document, gnome-doc-utils will generate additional elements
  245.       in the OMF file. For more information on this, please see the next
  246.       section, <xref linkend="settingup-document-name.xml" />.</para>
  247.  
  248.       <para>Where the documentation shows up in
  249.       <application>Yelp</application> depends on the category that you defined
  250.       in the <code>subject</code> element. You can see a list of valid
  251.       scrollkeeper categories at <ulink
  252.       url="http://scrollkeeper.sourceforge.net/documentation/categories.html">http://scrollkeeper.sourceforge.net/documentation/categories.html</ulink>.</para>
  253.  
  254.       <para>You can also get more information about what each element does by
  255.       referring to the <ulink
  256.       url="http://scrollkeeper.sourceforge.net/documentation/writing_scrollkeeper_omf_files/ar01s04.html#skomf-category">scrollkeeper
  257.       docs</ulink>.</para>
  258.     </section>
  259.  
  260.     <section>
  261.       <title>Setting up <filename
  262.       id="settingup-document-name.xml">help/C/document-name.xml</filename></title>
  263.  
  264.       <para>Create or move your help document to the location
  265.       <filename>help/C/document-name.xml</filename> (replacing
  266.       <literal>document-name</literal> with the actual document's name of
  267.       course).</para>
  268.  
  269.       <para>Then you will need to add the following elements/attributes to the
  270.       help document so that gnome-doc-utils will be able to populate the
  271.       autogenerated OMF files with the correct information. For more
  272.       information about where these elements should appear in the document,
  273.       you can refer to the excellent site <ulink
  274.       url="http://www.docbook.org/tdg/en/html/">http://www.docbook.org/tdg/en/html/</ulink>.<variablelist>
  275.           <varlistentry>
  276.             <term><abstract role="description">This application
  277.             is...</abstract></term>
  278.  
  279.             <listitem>
  280.               <para>Include this element in the
  281.               <code><articleinfo></code> section of your help document.
  282.               Gnome-doc-utils will use this information to create a
  283.               <code><description></code> element in the generated OMF
  284.               file.</para>
  285.             </listitem>
  286.           </varlistentry>
  287.  
  288.           <varlistentry>
  289.             <term><author>...</author></term>
  290.  
  291.             <listitem>
  292.               <para>Include this element (as well as firstname and surname
  293.               elements as children) in the <code><authorgroup></code>
  294.               section under the <code><articleinfo></code> element.
  295.               Gnome-doc-utils will use this information to create the
  296.               <code><creator></code> element in the generated OMF
  297.               file.</para>
  298.             </listitem>
  299.           </varlistentry>
  300.  
  301.           <varlistentry>
  302.             <term><author>, <corpauthor>, <editor>,
  303.             <othercredit>, or <publisher> with the attribute
  304.             role="maintainer"</term>
  305.  
  306.             <listitem>
  307.               <para>Include the attribute <code>role="maintainer"</code> on
  308.               one of these elements so that gnome-docs-utils creates a
  309.               <code><maintainer></code> element in the generated OMF
  310.               file.</para>
  311.             </listitem>
  312.           </varlistentry>
  313.  
  314.           <varlistentry>
  315.             <term><title> element of the <article> or
  316.             <articleinfo></term>
  317.  
  318.             <listitem>
  319.               <para>Gnome-doc-utils uses the contents of this element to
  320.               create the <code><title></code> element in the generated
  321.               OMF file.</para>
  322.             </listitem>
  323.           </varlistentry>
  324.  
  325.           <varlistentry>
  326.             <term><date> element in the last <revision> in your
  327.             <revhistory></term>
  328.  
  329.             <listitem>
  330.               <para>Gnome-doc-utils uses the contents of this element to
  331.               create the <code><date></code> element in the generated
  332.               OMF file.</para>
  333.             </listitem>
  334.           </varlistentry>
  335.  
  336.           <varlistentry>
  337.             <term><revnumber> element in the last <revision> in
  338.             your <revhistory></term>
  339.  
  340.             <listitem>
  341.               <para>Gnome-doc-utils uses the contents of this element to
  342.               create the <code><version></code> element in the generated
  343.               OMF file.</para>
  344.             </listitem>
  345.           </varlistentry>
  346.         </variablelist></para>
  347.  
  348.       <example id="example-omf-docbook">
  349.         <title>Example of DocBook file with required elements</title>
  350.  
  351.         <para>
  352.           <programlisting><?xml version="1.0" encoding="utf-8"?>
  353. <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
  354. "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
  355.   <!ENTITY legal SYSTEM "legal.xml">
  356.   <!ENTITY appversion "1.0">
  357.   <!ENTITY manrevision "1.0">
  358.   <!ENTITY date "February 2006">
  359.   <!ENTITY app "<application>My application</application>">
  360.   <!ENTITY appname "My GNOME App">
  361. ]>
  362.  
  363. <article id="index" lang="en">
  364.   <articleinfo>
  365.     <title>&appname; Manual</title>
  366.     <abstract role="description">
  367.       <para>&appname; is a program that ...</para>
  368.     </abstract>
  369.     <copyright>
  370.       <year>2006</year>
  371.       <holder>Brent Smith</holder>
  372.     </copyright>
  373.     <publisher>
  374.       <publishername> GNOME Documentation Project </publishername>
  375.     </publisher>
  376.  
  377.     &legal;
  378.  
  379.     <authorgroup>
  380.       <author role="maintainer">
  381.         <firstname>Brent</firstname>
  382.         <surname>Smith</surname>
  383.         <affiliation><orgname>GNOME Documentation Project</orgname></affiliation>
  384.       </author>
  385.     </authorgroup>
  386.  
  387.     <revhistory>
  388.       <revision>
  389.         <revnumber>&appname; Manual &manrevision;</revnumber>
  390.         <date>2006-02-04</date>
  391.       </revision>
  392.     </revhistory>
  393.  
  394.     <releaseinfo>This manual describes version &appversion; of &appname;</releaseinfo>
  395.   </articleinfo>
  396.   <section>
  397.     <title>Introduction</title>
  398.     <para>Foo</para>
  399.   </section>
  400. </article></programlisting>
  401.         </para>
  402.       </example>
  403.  
  404.       <para>The example in <xref linkend="example-omf-autogen" /> produces the
  405.       following omf file, when using the
  406.       <filename>document-name.omf.in</filename> file listed in <xref
  407.       linkend="example-omf-template" />.</para>
  408.  
  409.       <example id="example-omf-autogen">
  410.         <title>OMF file autogenerated by gnome-doc-utils</title>
  411.  
  412.         <screen><?xml version="1.0" encoding="utf-8"?>
  413. <omf>
  414.   <resource>
  415.     <creator>(Brent Smith)</creator>
  416.     <maintainer>(Brent Smith)</maintainer>
  417.     <title>My GNOME App Manual</title>
  418.     <date>2006-02-04</date>
  419.     <version identifier="My GNOME App Manual 1.0" date="2006-02-04"/>
  420.     <subject category="GNOME|Tutorials"/>
  421.     <description>
  422.       My GNOME App is a program that ...
  423.     </description>
  424.     <type>manual</type>
  425.     <format mime="" dtd="-//OASIS//DTD DocBook XML V4.1.2//EN"/>
  426.     <identifier url="file:///opt/gnome2/share/gnome/help/test/C/test.xml"/>
  427.     <language code="C"/>
  428.     <relation seriesid="b57e7e48-be78-11d6-85a3-d094906a987c"/>
  429.     <rights type="GNU FDL" license.version="1.1" holder="Shaun McCance"/>
  430.   </resource>
  431. </omf>
  432. </screen>
  433.       </example>
  434.     </section>
  435.  
  436.     <section>
  437.       <title>Removing Leftover Files</title>
  438.  
  439.       <para>If you are porting old documentation to gnome-doc-utils, then it
  440.       is recommended that you remove old
  441.       <filename>help/C/Makefile.am</filename> files, as well as any language
  442.       specific OMF files, such as <filename>help/C/document-name-C.omf or
  443.       <filename>help/<locale>/Makefile.am</filename>.</filename></para>
  444.     </section>
  445.  
  446.     <section>
  447.       <title>Adding New Files</title>
  448.  
  449.       <para>If you don't already have one, create a <filename>m4</filename>
  450.       directory in the toplevel directory, and create a
  451.       <filename>m4/.cvsignore</filename> file. Add both of these files to
  452.       CVS.</para>
  453.  
  454.       <para>Add a <filename>help/ChangeLog</filename>, analagous to
  455.       <filename>po/ChangeLog</filename>, which is used to track translations
  456.       and modifications to the help document. Also add this file to
  457.       CVS.</para>
  458.  
  459.       <para>Since gnome-doc-utils autogenerates <filename>.omf</filename>
  460.       files for each locale for which the help document is translated, you
  461.       will probably want to create and add a
  462.       <filename>help/.cvsignore</filename> and add this file to CVS.</para>
  463.     </section>
  464.  
  465.     <section>
  466.       <title>Modifying <filename>configure.ac</filename></title>
  467.  
  468.       <para>The following commands should be set in the
  469.       <filename>configure.ac</filename> file.<orderedlist>
  470.           <listitem>
  471.             <para>Add <filename>help/Makefile</filename> to
  472.             <function>AC_CONFIG_FILES</function> (or
  473.             <function>AC_OUTPUT</function> if you still use the old
  474.             method)</para>
  475.           </listitem>
  476.  
  477.           <listitem>
  478.             <para><function>AC_CONFIG_MACRO_DIR</function>(<parameter>[m4]</parameter>)</para>
  479.           </listitem>
  480.  
  481.           <listitem>
  482.             <para>
  483.               <function>GNOME_DOC_INIT</function>
  484.             </para>
  485.           </listitem>
  486.         </orderedlist></para>
  487.     </section>
  488.  
  489.     <section>
  490.       <title>Modifying the Toplevel <filename>Makefile.am</filename></title>
  491.  
  492.       <para>The following modifications should be made to the toplevel
  493.       <filename>Makefile.am</filename> file.</para>
  494.  
  495.       <orderedlist>
  496.         <listitem>
  497.           <para>Add gnome-doc-utils.make to
  498.           <varname>EXTRA_DIST</varname>.</para>
  499.         </listitem>
  500.  
  501.         <listitem>
  502.           <para>Add gnome-doc-utils.make to
  503.           <varname>DISTCLEANFILES</varname>.</para>
  504.         </listitem>
  505.  
  506.         <listitem>
  507.           <para>Add <code>--disable-scrollkeeper</code> to
  508.           <varname>DISTCHECK_CONFIGURE_FLAGS</varname>.</para>
  509.         </listitem>
  510.  
  511.         <listitem>
  512.           <para>Add m4 to EXTRA_DIST in the top-level Makefile.am</para>
  513.  
  514.           <note>
  515.             <para>You must remember to add <filename>m4</filename> to
  516.             <varname>EXTRA_DIST</varname> insite the top-level
  517.             <filename>Makefile.am</filename>, otherwise the directory won't be
  518.             added to the package and configure will fail (to catch this, you
  519.             must do <command>make distcheck</command> after <command>make
  520.             check</command>).</para>
  521.           </note>
  522.         </listitem>
  523.       </orderedlist>
  524.     </section>
  525.  
  526.     <section>
  527.       <title>Modifying the <filename>.cvsignore</filename> files</title>
  528.  
  529.       <para>Certain files are generated during the build process that you want
  530.       CVS to ignore when creating diffs and doing other functions. To make CVS
  531.       ignore these files:</para>
  532.  
  533.       <orderedlist>
  534.         <listitem>
  535.           <para>Add <filename>gnome-doc-utils.make</filename> to the top-level
  536.           <filename>.cvsignore</filename></para>
  537.         </listitem>
  538.  
  539.         <listitem>
  540.           <para>Add <filename>*.omf</filename> to the
  541.           <filename>help/.cvsignore</filename> file</para>
  542.         </listitem>
  543.       </orderedlist>
  544.     </section>
  545.  
  546.     <section>
  547.       <title>Testing</title>
  548.  
  549.       <para>To test and see if everything works:</para>
  550.  
  551.       <screen><prompt>$</prompt> <command>make && make check</command></screen>
  552.     </section>
  553.  
  554.     <section>
  555.       <title>Additional Steps</title>
  556.  
  557.       <para>There are just a few more steps to follow to finish migrating to
  558.       <application>gnome-doc-utils</application>:</para>
  559.  
  560.       <orderedlist>
  561.         <listitem>
  562.           <para>Add a <application>gnome-doc-utils</application> dependency
  563.           for your module in the <application>jhbuild</application>
  564.           moduleset.</para>
  565.         </listitem>
  566.  
  567.         <listitem>
  568.           <para>Migrate existing translations as described on <ulink
  569.           url="http://live.gnome.org/GnomeDocUtilsTranslationMigration">GnomeDocUtilsTranslationMigration</ulink>
  570.           (or just ask translators to do that for their own languages, since
  571.           this may be harder to do)</para>
  572.         </listitem>
  573.  
  574.         <listitem>
  575.           <para>Change status of your module on <ulink
  576.           url="http://live.gnome.org/GnomeDocUtilsMigration">GnomeDocUtilsMigration</ulink>
  577.           (if applicable).</para>
  578.         </listitem>
  579.       </orderedlist>
  580.     </section>
  581.  
  582.     <section>
  583.       <title>Let Us Know About it!</title>
  584.  
  585.       <para>We would definitely like to know if you port your documentation to gnome-doc-utils, so 
  586.       please send an email to the following mailing lists if you have converted (or started) using
  587.       <application>gnome-doc-utils</application> to manage your documentation.</para>
  588.  
  589.       <para>Let <ulink
  590.       url="mailto:gnome-doc-list@gnome.org">gnome-i18n@gnome.org</ulink> and <ulink
  591.       url="mailto:gnome-doc-list@gnome.org">gnome-doc-list@gnome.org</ulink> know
  592.       about it!</para>
  593.     </section>
  594.   </section>
  595.  
  596.   <include href="make-ref.xml" xmlns="http://www.w3.org/2001/XInclude" />
  597. </article>
  598.